home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / memory.doc < prev    next >
Text File  |  1993-07-05  |  10KB  |  486 lines
  1.  
  2.     MEMORY.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/memory/calloc
  7. c.lib/memory/cmpmem
  8. c.lib/memory/memcmp
  9. c.lib/memory/bcmp
  10. c.lib/memory/free
  11. c.lib/memory/malloc
  12. c.lib/memory/memcpy
  13. c.lib/memory/movmem
  14. c.lib/memory/bcopy
  15. c.lib/memory/realloc
  16. c.lib/memory/memset
  17. c.lib/memory/setmem
  18. c.lib/memory/clrmem
  19. c.lib/memory/bzero
  20.  
  21.  
  22. memory/calloc                        memory/calloc
  23.  
  24.    NAME
  25.     calloc    - allocate memory and clear
  26.  
  27.    SYNOPSIS
  28.     void *ptr = calloc(objsize, numobjs)
  29.     size_t objsize;
  30.     size_t numobjs;
  31.  
  32.    FUNCTION
  33.     Allocate memory and clear.  numobjs objects each objsize in size are
  34.     allocated contiguously and a pointer to the first object is
  35.     returned.  The memory is cleared to 0.
  36.  
  37.     Effectively this is equivalent to a malloc(objsize * numobjs); and
  38.     then a setmem(ptr, objsize * numobjs, 0); call.
  39.  
  40.     calloc returns NULL if the memory could not be allocated
  41.  
  42.    EXAMPLE
  43.     /*
  44.      *  allocate 16 objects and fill with junk
  45.      */
  46.  
  47.     #include <stdlib.h>
  48.     #include <assert.h>
  49.  
  50.     typedef struct {
  51.         long a, b, c;
  52.     } Junk;
  53.  
  54.     main()
  55.     {
  56.         Junk *jp;
  57.  
  58.         jp = calloc(sizeof(Junk), 16);
  59.         assert(jp);
  60.  
  61.         {
  62.         Junk *tj = jp;
  63.         short i;
  64.  
  65.         for (i = 0; i < 16; ++i, ++tj) {
  66.             tj->a = 1;
  67.             tj->b = 2;
  68.             tj->c = 3;
  69.         }
  70.         }
  71.         free(jp);
  72.         return(0);
  73.     }
  74.  
  75.    INPUTS
  76.     size_t objsize;     size of each object
  77.     size_t numobjs;     number of objects to allocate
  78.  
  79.    RESULTS
  80.     void *ptr;        pointer to first object
  81.  
  82.    SEE ALSO
  83.     malloc, strdup
  84.  
  85.  
  86. memory/cmpmem                        memory/cmpmem
  87. memory/memcmp                        memory/memcmp
  88. memory/bcmp                        memory/bcmp
  89.  
  90.    NAME
  91.     cmpmem    - compare two memory buffers
  92.     memcmp    - compare two memory buffers (ANSI)
  93.     bcmp    - compare two memory buffers (UNIX)
  94.  
  95.    SYNOPSIS
  96.     int r = cmpmem(s1, s2, bytes)
  97.     int r = memcmp(s1, s2, bytes)
  98.     int r = bcmp(s1, s2, bytes)
  99.     void *s1;
  100.     void *s2;
  101.     size_t bytes;
  102.  
  103.    FUNCTION
  104.     compare two memory buffers.  A byte by byte (unsigned) compare is
  105.     done.  When a compare fails and the byte in s1 is less than the
  106.     byte in s2 then -1 is returned.  If the byte in s1 is greater than
  107.     the byte in s2 then 1 is returned.
  108.  
  109.     If the count is exhausted and all compares succeed then 0 is
  110.     returned indicating the two buffers are the same.
  111.  
  112.    EXAMPLE
  113.     #include <stdlib.h>
  114.     #include <assert.h>
  115.  
  116.     main()
  117.     {
  118.         unsigned char buf1[4];
  119.         unsigned char buf2[4];
  120.         int r;
  121.  
  122.         buf1[0] = 0;    buf2[0] = 0;
  123.         buf1[1] = 10;    buf2[1] = 10;
  124.         buf1[2] = 15;    buf2[2] = 15;
  125.         buf1[3] = 4;    buf2[3] = 4;
  126.  
  127.         r = memcmp(buf1, buf2, 4);
  128.         assert(r == 0);
  129.  
  130.         buf1[2] = 12;
  131.         r = memcmp(buf1, buf2, 4);
  132.         assert(r < 0);
  133.  
  134.         buf1[2] = 200;
  135.         r = memcmp(buf1, buf2, 4);
  136.         assert(r > 0);
  137.         return(0);
  138.     }
  139.  
  140.    INPUTS
  141.     void *s1;        pointer to first buffer
  142.     void *s2;        pointer to second buffer
  143.     size_t bytes;        size of each buffer
  144.  
  145.    RESULTS
  146.     int r;            -1 if buf s1 < buf s2, 0 if buf s1 == buf s2,
  147.                 1 if buf s1 > buf s2.
  148.  
  149.    SEE ALSO
  150.     memset, setmem, bzero, clrmem, bcopy, movmem, memcpy, memmove
  151.  
  152.  
  153. memory/free                        memory/free
  154.  
  155.    NAME
  156.     free    - free memory allocated by calloc(), malloc(), or strdup().
  157.  
  158.    SYNOPSIS
  159.     void free(ptr);
  160.     void *ptr;
  161.  
  162.    FUNCTION
  163.     free memory allocated by calloc(), malloc(), or strdup().
  164.  
  165.     IT IS ILLEGAL TO FREE(NULL).  If free() is given an illegal pointer
  166.     or NULL it will freeze the process by calling Wait(0L).
  167.  
  168.    EXAMPLE
  169.     see calloc() example
  170.  
  171.    INPUTS
  172.     void *ptr;        pointer to memory to free
  173.  
  174.    RESULTS
  175.     none
  176.  
  177.    SEE ALSO
  178.     malloc, calloc, strdup
  179.  
  180.  
  181. memory/malloc                        memory/malloc
  182.  
  183.    NAME
  184.     malloc    - allocate memory, the memory is NOT automatically cleared
  185.  
  186.    SYNOPSIS
  187.     void *ptr = malloc(bytes);
  188.     size_t bytes;
  189.  
  190.    FUNCTION
  191.     malloc allocates the specified number of bytes of memory.  The
  192.     returned pointer is longword aligned.
  193.  
  194.     malloc returns NULL if the memory could not be allocated.  Note
  195.     that, unlike calloc, malloc does NOT ZERO THE MEMORY it
  196.     returns.
  197.  
  198.    EXAMPLE
  199.     /*
  200.      *  allocate 16 objects and fill with junk, same as calloc example
  201.      *  but uses malloc instead.  Note that using malloc has the
  202.      *  advantage of not having to do a run time multiplication (and
  203.      *  possibly not bring in _muls or _mulu from c.lib to accomplish
  204.      *  this)
  205.      */
  206.  
  207.     #include <stdlib.h>
  208.     #include <assert.h>
  209.  
  210.     typedef struct {
  211.         long a, b, c;
  212.     } Junk;
  213.  
  214.     main()
  215.     {
  216.         Junk *jp;
  217.  
  218.         jp = malloc(sizeof(Junk) * 16);
  219.         assert(jp);
  220.  
  221.         setmem(jp, sizeof(Junk) * 16, 0);
  222.  
  223.         {
  224.         Junk *tj = jp;
  225.         short i;
  226.  
  227.         for (i = 0; i < 16; ++i, ++tj) {
  228.             tj->a = 1;
  229.             tj->b = 2;
  230.             tj->c = 3;
  231.         }
  232.         }
  233.         free(jp);
  234.         return(0);
  235.     }
  236.  
  237.    INPUTS
  238.     size_t bytes;        number of bytes to allocate
  239.  
  240.    RESULTS
  241.     void *ptr;        pointer to base of allocated memory.  The memory
  242.                 is not zerod.
  243.  
  244.    SEE ALSO
  245.     calloc, strdup
  246.  
  247.  
  248. memory/memcpy                        memory/memcpy
  249. memory/movmem                        memory/movmem
  250. memory/bcopy                        memory/bcopy
  251. memory/memmove                        memory/memmove
  252.  
  253.    NAME
  254.     memcpy    - copy memory  ANSI, does not work with overlapped memory buffers
  255.     memmove - copy memory  ANSI, works with overlapped memory buffers
  256.     movmem    - copy memory         works with overlapped memory buffers
  257.     bcopy    - copy memory  UNIX, works with overlapped memory buffers
  258.  
  259.    SYNOPSIS
  260.     void *ptr = memcpy(d, s, bytes);
  261.     void *ptr = memmove(d, s, bytes);
  262.     void *ptr = movmem(s, d, bytes);
  263.     void *ptr = bcopy(s, d, bytes);
  264.  
  265.     void *d;
  266.     void *s;
  267.     size_t bytes;
  268.  
  269.    FUNCTION
  270.     these functions copy memory from one region to another.  Unlike
  271.     string routines these functions do not stop the copy when a nul
  272.     is encountered.
  273.  
  274.    NOTE
  275.     DICE's memory move optimizes the copy using movem when possible,
  276.     yielding very fast memory copies for large buffers.
  277.  
  278.    WARNING
  279.     BE CAREFUL about argument ordering.  Some calls take the source
  280.     buffer first and other calls take the destination buffer first.
  281.  
  282.     The ANSI committee really screwed up its standard, going for a
  283.     destination, source ordering rather than the more logical
  284.     source, destination ordering.  Thus, many programmers will use
  285.     the non-standard movmem() call instead of the ANSI memmove() call.
  286.  
  287.     The ANSI function 'memcpy' as defined by the ANSI standard cannot
  288.     handle overlapped memory areas.  The Amiga implementation can but
  289.     you should remember this if you intend to port your code.
  290.  
  291.     The UNIX bcopy call exists for compatibility purposes and should
  292.     not be used with new programs.
  293.  
  294.    EXAMPLE
  295.     /*
  296.      *  This example copies the entire buffer, not just the part
  297.      *  containing the string.  Normally one just uses string routines.
  298.      */
  299.  
  300.     #include <string.h>
  301.     #include <assert.h>
  302.  
  303.     main()
  304.     {
  305.         char s[16];
  306.         char d[16];
  307.         void *p;
  308.  
  309.         strcpy(s, "This is a test");
  310.  
  311.         p = movmem(s, d, sizeof(s));
  312.         assert(p == d);
  313.         puts(d);
  314.  
  315.         strcpy(s, "FuBarBletch");
  316.         p = bcopy(s, d, sizeof(s));
  317.         assert(p == d);
  318.         puts(d);
  319.  
  320.         strcpy(s, "EchoBeko");
  321.         p = memcpy(d, s, sizeof(s));
  322.         assert(p == d);
  323.         puts(d);
  324.  
  325.         strcpy(s, "GakFuBar");
  326.         p = memmove(d, s, sizeof(s));
  327.         assert(p == d);
  328.         puts(d);
  329.  
  330.         return(0);
  331.     }
  332.  
  333.  
  334.    INPUTS
  335.     void *s;        source buffer
  336.     void *d;        destination buffer
  337.  
  338.    RESULTS
  339.     void *ptr;        pointer to the destination buffer (d)
  340.  
  341.    SEE ALSO
  342.     memset, setmem, bzero, clrmem, cmpmem, memcmp,
  343.     strcpy, strncpy
  344.  
  345.  
  346.  
  347. memory/realloc                        memory/realloc
  348.  
  349.    NAME
  350.     realloc - reallocate memory allocated by calloc, malloc, or strdup
  351.  
  352.    SYNOPSIS
  353.     void *newptr = realloc(oldptr, bytes)
  354.     void *oldptr;
  355.     size_t bytes;
  356.  
  357.    FUNCTION
  358.     realloc reallocates a previously allocated buffer, making it
  359.     larger or smaller.  realloc returns a pointer to a new buffer
  360.     which might be the same as the old buffer, but might not.
  361.  
  362.     data in the original buffer is copied to the new buffer and
  363.     the original buffer is freed.  When extending a buffer with
  364.     realloc note that the extended bytes (beyond the original buffer)
  365.     will come up garbage.
  366.  
  367.     You may pass a NULL as the first argument to realloc which basically
  368.     makes realloc a malloc.
  369.  
  370.    EXAMPLE
  371.     #include <string.h>
  372.     #include <assert.h>
  373.     #include <stdlib.h>
  374.  
  375.     main()
  376.     {
  377.         char *s;
  378.         int len;
  379.  
  380.         s = strdup("This is a test");
  381.         assert(s);
  382.  
  383.         len = strlen(s);
  384.  
  385.         /*
  386.          *    Remember that len does not include the nul byte at the end
  387.          *    of the string
  388.          */
  389.  
  390.         s = realloc(s, len + 8);        /*  make more room */
  391.         assert(s);
  392.  
  393.         /*
  394.          *    we can use strcat since in extending the allocated string
  395.          *    the nul *was* copied along with the string during the realloc.
  396.          */
  397.  
  398.         strcat(s, "xx");
  399.  
  400.         puts(s);        /*  This is a testxx    */
  401.  
  402.         return(0);
  403.     }
  404.  
  405.  
  406.    INPUTS
  407.     void *oldptr;        pointer to original allocated buffer
  408.     size_t bytes;        size of new buffer
  409.  
  410.    RESULTS
  411.     void *newptr;        pointer to new buffer
  412.  
  413.    SEE ALSO
  414.     malloc, calloc, strdup
  415.  
  416.  
  417. memory/memset                        memory/memset
  418. memory/setmem                        memory/setmem
  419. memory/clrmem                        memory/clrmem
  420. memory/bzero                        memory/bzero
  421.  
  422.    NAME
  423.     memset    -   ANSI    set memory buffer to a byte value
  424.     setmem    -   DEFACTO set memory buffer to a byte value
  425.     clrmem    -   DICE    zero out a memory buffer
  426.     bzero    -   UNIX    zero out a memory buffer
  427.  
  428.    SYNOPSIS
  429.     void *ptr = memset(buf, c, n);
  430.     void *ptr = setmem(buf, n, c);
  431.     void *ptr = clrmem(buf, n);
  432.     void *ptr = bzero(buf, n);
  433.  
  434.     void *buf;
  435.     int c;
  436.     size_t n;
  437.  
  438.    FUNCTION
  439.     fill a memory buffer with the specified character, c.  c is
  440.     converted to an unsigned char by the fill routine before beginning
  441.     the fill.  n bytes are filled.
  442.  
  443.    WARNING
  444.     Again, watch out for argument ordering, especially for the
  445.     ANSI memset() call.  Again, the ANSI committee really screwed
  446.     up the call ordering so there is another defacto standard
  447.     call called setmem().
  448.  
  449.     bzero() exists for UNIX compatibility, and clrmem() is yet another
  450.     call (this time introduced by DICE, sorry! :-)).
  451.  
  452.     memset() and setmem() are the most portable calls.
  453.  
  454.    EXAMPLE
  455.     #include <string.h>
  456.     #include <assert.h>
  457.     #include <stdlib.h>
  458.  
  459.     main()
  460.     {
  461.         char buf[32];
  462.         char *b;
  463.  
  464.         b = setmem(buf, 32, 0);
  465.         assert(b == buf);
  466.  
  467.         b = setmem(buf, 4, 'a');
  468.         b = memset(buf + 4, 'b' , 4);
  469.         puts(buf);      /*  aaaabbbb    */
  470.  
  471.         return(0);
  472.     }
  473.  
  474.  
  475.    INPUTS
  476.     void *buf;        pointer to buffer to fill
  477.     int c;            character to copy into buffer (setmem, memset)
  478.     size_t n;        # of bytes to fill
  479.  
  480.    RESULTS
  481.     void *ptr;        pointer to buffer (== buf).
  482.  
  483.    SEE ALSO
  484.     malloc, calloc, strdup, movmem, cmpmem
  485.  
  486.